## Summary

- **New page**: \`docs/concepts/principals.md\` — the five principal
classes and how caller identity works (self-authenticating IDs, canister
IDs, anonymous principal, management canister, derived IDs)
- **Expanded**: \`docs/concepts/canisters.md\` — added two sections:
- "Controllers" now includes the full control structure table
(centralized / multi-sig / SNS-governed / immutable) and immutability
verification
- "### Upgrade" now includes the 3-step upgrade hook sequence
(pre\_upgrade → install → post\_upgrade) and trap behavior
- "Inter-canister messaging and error handling" covers the actor model,
bidirectional request/reply, guaranteed reply, and trap/rollback
semantics
- **Fixed**: \`docs/concepts/canisters.md\` line 73 — replaced Learn Hub
principal link with internal \`principals.md\` link
- **Updated**: \`docs/concepts/index.md\` — added principals.md entry
under Architecture with accurate description
- **Updated**: \`docs/references/glossary.md\` — updated principal entry
to link to \`concepts/principals.md\`
- **Deleted**: 4 consumed Learn Hub staging files from
\`canister-smart-contracts/\`

## Content placement rationale

The "Canister Control" Learn Hub article was grouped with "What is a
Principal?" in Learn Hub navigation, but the content (controller table,
upgrade hooks) belongs with canisters under Diataxis. \`principals.md\`
is focused on identity only; \`canisters.md\` absorbs all canister
management content.

The "Computational Model" article is fully migrated into
\`canisters.md\` (actor model, bidirectional messaging, guaranteed
reply, trap/rollback in "Inter-canister messaging and error handling").

## Staging files deleted

-
\`.migration/learn-hub/how-does-icp-work/canister-smart-contracts/{what-is-a-principal,canister-control,canister-smart-contracts,computational-model}.md\`

## Sync recommendation

\`principals.md\`: \`informed by Learn Hub article "What is a
Principal?" (migrated, source retired)\`
\`canisters.md\` additions: \`informed by Learn Hub articles "Canister
Smart Contracts", "Computational Model", "Canister Control" (migrated,
source retired)\`

…ocs (#208)

## Summary

Migrates all 57 developer-relevant articles from the Learn Hub \"How
does ICP work?\" section into the developer docs, replacing Learn Hub as
the canonical source for ICP protocol concepts before the site is
retired.

This was executed as 9 content batch PRs plus a post-migration review
pass, all merged into this staging branch before landing on `main`:

**Batch 1 — Protocol stack** (#209): Consensus, peer-to-peer, message
routing, execution layer, state synchronization, and performance concept
pages under `docs/concepts/protocol/`.

**Batch 2 — Node infrastructure** (#210):
`docs/concepts/node-infrastructure.md` — TEE (SEV-SNP) attestation,
IC-OS layer model (SetupOS / HostOS / GuestOS), TEE key derivation and
disk encryption.

**Batch 3 — Edge infrastructure** (#211):
`docs/concepts/edge-infrastructure.md` — boundary nodes, HTTP gateway,
edge caching.

**Batch 4 — Evolution and scaling** (#212):
`docs/concepts/evolution-scaling.md` — horizontal scaling via subnet
sharding, fault tolerance, governance-driven subnet creation, forkless
protocol upgrades.

**Chain fusion deep dives** (#213): Expanded
`docs/concepts/chain-fusion/` with dedicated pages for Bitcoin
integration, ckBTC mechanics, Ethereum integration, EVM RPC, Solana RPC,
Dogecoin integration, and Exchange Rate Canister. Architecture and flow
diagrams migrated to `public/concepts/chain-fusion/`.

**Cryptography deep dives** (#214): Expanded
`docs/concepts/chain-key-cryptography.md` and
`docs/concepts/certified-data.md` with subnet keys, threshold signing
internals, and certified communication theory.

**Tokens, ledgers, and cycles** (#215): Expanded
`docs/concepts/ledgers.md` and `docs/concepts/cycles.md` with ledger
architecture, accounts, sub-accounts, cycles ledger transfer semantics,
and NNS tokenomics.

**Governance deep dives** (#216): Expanded `docs/concepts/governance.md`
and added `docs/concepts/sns-framework.md` — NNS neuron attributes and
bonuses, voting rewards formula, Neurons Fund, proposal taxonomy, SNS
framework and architecture, DAO settings, launch flow, SNS neurons and
rewards, and SNS proposals.

**Principals and canister model** (#217): Expanded
`docs/concepts/principals.md` and `docs/concepts/canisters.md` —
principal model, canister control, Wasm execution model, and
`docs/concepts/app-architecture.md`.

**Post-migration holistic review** (#218, #226):
- Navigation restructured across all concepts, guides, and references —
sentence case applied throughout, section indices completed
- Cross-reference audit: all Learn Hub outbound links replaced with
internal doc links; first-use terms linked to their concept pages
- Glossary expanded with TEE, boundary node, and cycle-related entries
- System canisters content placement corrected
- Exchange Rate Canister restructured across concept, reference, and
guide pages (#XRC commits)

**Migration infrastructure** (initial prep commits):
- `.docs-plan/learn-hub-migration.md` — agent workflow and authoring
rules for 9-batch execution
- `.docs-plan/learn-hub-navigation.md` — per-article mapping (target
file, action type, cross-link table)
- `AGENTS.md / CLAUDE.md` — Learn Hub removed from external-docs list;
linking rule updated
- `sidebar.mjs` — all new concept pages registered

## Closes

- Closes #187 — Content gap analysis: Learn Hub vs developer docs
- Closes #190 — Gap analysis: articles on learn.internetcomptuter.org vs
developer-docs `reference` and `concepts`
- Closes #226 — Post-migration holistic review (content placement, nav
structure, glossary, first-use terms)

## Sync recommendation

hand-written (all pages authored from Learn Hub source articles via
Zendesk API; no upstream repo to sync from)

<!-- Upstream: source articles fetched from learn.internetcomputer.org
via Zendesk API (2026-05-06 through 2026-05-11) -->